The SURFACE function returns a reference to the created graphic. Use the returned reference to manipulate the graphic after creation by changing properties or calling methods.

Arguments

Z

A two-dimensional array containing the surface heights.

X

A vector or 2D array containing the x-coordinates of the Z data. If X is a vector, then each element specifies the x-coordinate for a column of Z. If X is a two-dimensional array, then each element specifies the x-coordinate of the corresponding point in Z.

Y

A vector or 2D array containing the y-coordinates of the Z data. If Y is a vector, then each element specifies the y-coordinate for a row of Z. If Y is a two-dimensional array, then each element specifies the y-coordinate of the corresponding point in Z.

Keywords

Keywords are applied only during the initial creation of the graphic.

AXIS_STYLE

Set this keyword to one of the following values:

0 - No axes. This is the default for images.
1 - Single X, Y (and Z if 3D) axes located at the minimum data value. This is the default for 3D graphics.
2 - Box axes - multiple axes located at both the minimum and maximum data values. This is the default for 2D graphics.
3 - Crosshair-style axes - located at the midpoint of each data dimension. This is the default for polar plots.

You can set the following properties on the axes:

Property	Description
[XYZ]COLOR	A string or RGB vector containing the axis color.
[XYZ]GRIDSTYLE	A string or integer giving the linestyle for tickmarks.
[XYZ]LOG	Set to 1 if the axis is logarithmic.
[XYZ]MAJOR	The number of major tick marks. Set to -1 to auto-compute, set to 0 to suppress.
[XYZ]MINOR	The number of minor tick marks. Set to -1 to auto-compute, set to 0 to suppress.
[XYZ]SHOWTEXT	Set to 1 to show text labels or 0 to hide the text labels.
[XYZ]STYLE	The axis range style. The valid values are: (0) "Nice" range. Default for all graphics except Image, Barplot, and Map. (1) Force the exact data range. Default for Image, Barplot, and Map. (2) Pad the axes slightly beyond the "nice" range. (3) Pad the axes slightly beyond the exact data range. Note: The [XYZ]RANGE takes precedence over this property.
[XYZ]SUBTICKLEN	The ratio of the minor tick length to the major tick length. The default is 0.5.
[XYZ]TEXT_COLOR	A string or RGB vector containing the axis text color.
[XYZ]TEXT_ORIENTATION	The angle (in degrees) of the tick mark labels.
[XYZ]TEXTPOS	Set to 1 to position text above the axis. The default is 0, below the axis.
[XYZ]THICK	Set to a floating-point value between 0 and 10 to specify the line thickness for tickmarks. A thickness of 0 gives a thin hairline. The default is 1.
[XYZ]TICKDIR	Set to 1 to draw the tickmarks facing outwards. The default is 0, facing inwards.
[XYZ]TICKFONT_NAME	A string containing the font name for the axis text.
[XYZ]TICKFONT_SIZE	The axis text size in points.
[XYZ]TICKFONT_STYLE	A string or integer containing the font style: "normal" (0), "bold" (1), "italic" (2), or "bold italic" (3).
[XYZ]TICKFORMAT	A string or string array of tick label formats.
[XYZ]TICKINTERVAL	The interval between major tick marks.
[XYZ]TICKLAYOUT	Set to 1 to suppress tick marks; set to 2 to draw a box around the tick labels.
[XYZ]TICKLEN	The normalized length of each major tick mark. Tick lengths < 0.25 are in arbitrary units that do not scale with the graphic. Larger tick lengths are normalized relative to the width of the graphic. The default is 0.05.
[XYZ]TICKNAME	A string array containing the tick labels.
[XYZ]TICKUNITS	A string giving the tick units. Valid values are "" (the default), "Years", "Months", "Days", "Hours", "Minutes", "Seconds", "Time", or "exponent" for exponential notation. If any of the time units are utilized, then the tick values are interpreted as Julian date/time values. If more than one unit is provided, the axis will be drawn with multiple levels.
[XYZ]TICKVALUES	An array of tick mark locations.
[XYZ]TITLE	A string giving the axis title.
[XYZ]TRANSPARENCY	An integer from 0-100 giving the percent transparency.

For more detailed explanations of these properties, see the AXIS function.

Tip: You can also use the AXIS function to insert additional axes after the graphic has been created.

BUFFER

Set this keyword to 1 to direct the graphics to an off-screen buffer instead of creating a window.

CURRENT

Set this keyword to create the graphic in the current window. If no window exists, a new window is created. The WINDOW's SetCurrent method may be used to set the current window.

DEVICE

Set this keyword if values are specified in device coordinates (pixels) for MARGIN and POSITION. (Normalized coordinates are the default for these keywords.)

DIMENSIONS

Set this keyword to a two-element vector of the form [width, height] to specify the window dimensions in pixels. If you do not specify a value for DIMENSIONS, IDL by default uses the values of the IDL_GR_WIN_HEIGHT and IDL_GR_WIN_WIDTH preferences for Windows platforms or the IDL_GR_X_HEIGHT and IDL_GR_X_WIDTH preferences for X Windows systems on UNIX.

LAYOUT

Set this keyword to a three-element vector [ncol, nrow, index] that arranges graphics in a grid. The first dimension ncol is the number of columns in the grid, nrow is the number of rows, and index is the grid position at which to place the graphic (starting at element 1). This keyword is ignored if either OVERPLOT or POSITION is specified.

LOCATION

Set this keyword to a two-element vector [X offset, Y offset] giving the window's screen offset in pixels.

MARGIN

Set this keyword to the current graphic’s margin values in the layout specified by the LAYOUT property. Use a scalar value to set the same margin on all sides, or use a four-element vector [left, bottom, right, top] to specify different margins on each side.

By default, margin values are expressed in normalized units ranging from 0.0 to 0.5. If the DEVICE keyword is set, the values are given in device units (pixels).

This keyword is ignored if either OVERPLOT or POSITION is specified.

NODATA

Set this keyword to 1 to create the graphic, but without any data attached to it. The axes and title (if present) are also created and displayed. If the OVERPLOT keyword is specified, axis ranges will not change.

Note: You must still provide valid input arguments. The data range of the input arguments are used to automatically set the range of the axes. The [XYZ]RANGE properties may be used to override these default ranges.

OVERPLOT

Set this keyword to 1 (one) to place the graphic on top of the existing graphic in the current window. If no current window exists, a new window is created. Set this keyword to an existing IDL Graphic reference to direct the new graphic to the window specified by the provided IDL Graphic reference.

POSITION

Set this keyword to a four-element vector that determines the location of the visualization within the graphic window. The coordinates x₀, y₀ represent the lower left and x₁, y₁ represent the upper right corners of the data space. Coordinates are expressed in normalized units ranging from 0.0 to 1.0. If the DEVICE property is set, the units are given in device units (pixels).

Note: When using POSITION, factor in enough space to display the title and axis labels. For example, if you use POSITION to place your visualization at 0 on the X or Y axis, any labels for that axis will not be visible.

TEXTURE_IMAGE

Set this keyword to an array containing an image to be texture mapped onto the surface. If this property is omitted, no texture map is applied and the surface is filled with the color specified by the COLOR or VERTEX_COLORS property. The image array can be a two-dimensional array of color indexes or a three-dimensional array specifying RGB values (3 x n x m, n x 3 x m, or n x m x 3) or RGBA values (4 x n x m, n x 4 x m, or n x m x 4).

WINDOW_TITLE

Set this keyword to the title of the IDL Graphic window. The title is displayed in the window's title bar.

Properties

ANTIALIAS

By default anti-aliasing is used when drawing lines for mesh or ruled style. Set this property to 0 to disable anti-aliasing.

ASPECT_RATIO

A floating point value indicating the ratio of the Y dimension to the X dimension in data units. If this property is set to a nonzero value, the aspect ratio will be preserved as the graphic is stretched or shrunk. The default value is 0, meaning that the aspect ratio is not fixed, but is allowed to change as the graphic is stretched or shrunk.

ASPECT_Z

A floating point value indicating the ratio of the Z dimension to the X and Y dimensions, in data units. If this is a nonzero value, the aspect ratio will be preserved as the graphic is stretched or shrunk. The default value is 0, meaning that the aspect ratio is not fixed, but is allowed to change as the graphic is stretched or shrunk.

AXES (Get Only)

This property retrieves an array that contains all of the AXIS objects within the visualization. For example, for a plot visualization:

p = PLOT(/TEST)

ax = p.AXES

ax[0].TITLE = 'X axis'

ax[1].TITLE = 'Y axis'

ax[2].HIDE = 1 ; hide top X axis

ax[3].HIDE = 1 ; hide right Y axis

See AXIS for a list of the available properties.

BACKGROUND_COLOR

Set this property to a string or RGB vector indicating the graphic's background color. The default value is [255, 255, 255] (white). Set this property to a scalar value to remove the background color.

Tip: To set the background color of the entire window, retrieve the window object using the WINDOW property, and set the BACKGROUND_COLOR on the window object.

BACKGROUND_TRANSPARENCY

Set this property to an integer between 0 and 100 giving the percent transparency of the background color. The default is 100 (completely transparent).

Note: If the BACKGROUND_COLOR property is changed, and the current background transparency is 100, then the BACKGROUND_TRANSPARENCY will be automatically set to 0 (opaque) so that you can see the new color.

BOTTOM_COLOR

Set this property to a string or RGB vector that specifies the surface bottom color. The default behavior is to make the bottom color match the COLOR property.

CLIP

Set this property to 1 to clip portions of the graphic that lie outside of the dataspace range, or to 0 to disable clipping. The default is 1.

COLOR

Set this property to a string or RGB vector that specifies the surface color.

Note: When you retrieve the COLOR property, the returned value will always be a three-element RGB vector, regardless of how the color was initially specified.

CROSSHAIR (Get Only)

Use this property to retrieve a reference to the Crosshair graphic. All graphics objects within the same set of axes share a single Crosshair graphic. For Plot graphics the default behavior is to display the crosshair when the plot is selected. For other graphics the crosshair is disabled. The STYLE property may be used to control the automatic crosshair display, while the LOCATION property is used to manually draw a crosshair.

You can get and set the following properties on the retrieved crosshair:

Property	Description
ANTIALIAS	Set to 1 to enable anti-aliasing for the lines.
COLOR	A string or RGB vector containing the color.
HIDE	Set to 1 to hide the crosshair, 0 to show.
INTERPOLATE	Set to 1 to force interpolation between Plot data points when SNAP is active. For other graphics this property is ignored. The default is 0.
LINESTYLE	An integer or string giving the line style. The default is 'dot'.
LOCATION	The location at which to draw the crosshair. For Plot graphics, if SNAP is enabled, then only the X coordinate needs to be supplied. Otherwise, LOCATION should be set to a two-element vector [X, Y] for two-dimensional graphics or [X, Y, Z] for three-dimensional graphics. If STYLE is currently "None", then setting the LOCATION will automatically set the STYLE to "Manual".
NAME	The name of the graphic.
SNAP	Set to 1 to snap the crosshair to the nearest Plot data point. For other graphics this property is ignored. The default is 1.
STYLE	An integer or string giving the crosshair style. Possible values are: 0 - "None" - never draw the crosshair. This is the default. 1 - "Manual" - draw the crosshair using the LOCATION property. 2 - "Auto" - automatically draw the crosshair. This is the default for plots.
THICK	The thickness of the lines. The default is 1.
TRANSPARENCY	The percent transparency of the lines. The default is 50.
UVALUE	An IDL variable of any data type.

For example, use the CROSSHAIR property to draw a crosshair on an image:

im = IMAGE(/TEST, TRANSPARENCY=50, AXIS_STYLE=2)

c = im.CROSSHAIR

c.COLOR = 'red'

c.THICK = 2

c.LOCATION = [300, 200]

See Creating Mouse Event Functions for a more detailed crosshair example.

DEPTH_CUE

Set this property to a two-element vector [bright, dim] specifying the near and far planes for depth cueing, in normalized units. Depth cueing causes graphics objects that are further away to fade into the background. The first element is where the fade starts to take effect, while the second element is where the objects are completely transparent. Negative values are closer to the eye, while positive values are farther from the eye. The default value is [0, 0] which disables depth cueing. A typical value would be [0, 1], which would cause objects to start to fade at the mid-plane of the window, and completely fade out at a normalized eye distance of 1.

FONT_COLOR

Set this property to a string or RGB vector that specifies the text color for the title and axes (if present). The default value is "black".

FONT_NAME

Set this property equal to a string specifying the IDL or system font for the title and axes (if present). The default value is “Helvetica”.

FONT_SIZE

Set this property equal to an integer specifying the font size for the title and axes (if present). The default value is 16 points.

FONT_STYLE

Set this property equal to an integer or a string specifying the font style for the title and axes (if present). Allowed values are:

Integer	String	Resulting Style
0	"Normal" or "rm"	Default (roman)
1	"Bold" or "bf"	Bold
2	"Italic" or "it"	Italic
3	"Bold italic" or "bi"	Bold italic

HIDDEN_LINES

Set this property to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled.

HIDE

Set this property to 1 to hide the graphic. Set HIDE to 0 to show the graphic.

LINESTYLE

An integer or string specifying the line style for the surface if the surface style is set to "Mesh", "RuledXZ", "RuledYZ", or "Lego". The allowed values are:

Index	String (case insensitive)
0	'solid' or '-'(dash)
1	'dot' or ':'(colon)
2	'dash' or '--' (double dashes)
3	'dash dot' or '-.'
4	'dash dot dot dot' or '-:'
5	'long dash' or '__' (double underscores)
6	'none' or ' ' (space)

MAX_VALUE

The maximum value to be plotted. If this property is set, data values greater than the value of MAX_VALUE are treated as missing data and are not plotted.

Note: The IEEE floating point value NaN is also treated as missing data.

MIN_VALUE

The minimum value to be plotted. If this property is set, data values less than the value of MIN_VALUE are treated as missing data and are not plotted.

Note: The IEEE floating point value NaN is also treated as missing data.

NAME

A string that specifies the name of the graphic. The name can be used to retrieve the graphic using the brackets array notation. If NAME is not set then a default name is chosen based on the graphic type.

PERSPECTIVE

Set this property to 1 to enable a perspective graphics projection. In the perspective projection, objects that are further away will appear smaller. The default is 0, which is the orthogonal perspective.

RGB_TABLE

The number of the predefined IDL color table, or a 3 x 256 or 256 x 3 byte array containing color values to use for vertex colors. If the values supplied are not of type byte, they are scaled to the byte range using BYTSCL. Use the VERT_COLORS property to specify indices that select colors from the values specified with RGB_TABLE.

SHADING

Set this property to 1 to use Gouraud shading, or to 0 (the default) to use flat shading. In flat shading the color has a constant intensity for each face of the surface, based on the normal vector. In Gouraud shading the colors are interpolated between vertices, and then along scanlines from each of the edge intensities. Gouraud shading may be slower than flat shading, but results in a smoother appearance.

SHOW_SKIRT

Set this property to 1 to draw a skirt around the edges of the surface, at the given SKIRT value. Set to 0 (the default) to disable drawing the skirt.

SKIRT

Set this property to the Z value of the bottom of the skirt. On creation, if SKIRT is set, then SHOW_SKIRT will automatically be set to 1.

STYLE

Set this property equal to an integer or a case-insensitive string specifying the surface style. Allowed values are:

Integer	String
0	"Points"
1	"Mesh"
2	"Filled" (the default)
3	"RuledXZ"
4	"RuledYZ"
5	"Lego"
6	"LegoFilled"

TEXTURE_INTERP

Set this property to a nonzero value to indicate that bilinear sampling is to be used with texture mapping. The default method is nearest-neighbor sampling.

THICK

Set this property to a value between 0 and 10 that specifies the line thickness of the surface lines. A thickness of 0 displays a thin hairline on the chosen device. The default value is 1.

TITLE

Set this property to a string specifying a title. The title properties may be modified using FONT_COLOR, FONT_NAME, FONT_SIZE, and FONT_STYLE. After creation the TITLE property may be used to retrieve a reference to the title text object, and the TEXT properties may be used to modify the title object.

You can also add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols.

TRANSPARENCY

An integer between 0 and 100 that specifies the percent transparency of the plot line. The default value is 0.

UVALUE

Set this property to an IDL variable of any data type.

VERT_COLORS

A vector of colors to be used to specify the color of a surface vertex. The vector may be of the form [n*m] or [n, m] where each entry is a color index, or of the form [3,n*m] where each 3-element row is an RGB color, or of the form [4,n*m] where each 4-element row is an RGBA color. To remove vertex colors after they have been set, set VERT_COLORS to a scalar. If VERT_COLORS is not specified, the entire surface is drawn in the single color provided by the COLOR property, which is the default action. If this keyword is set to a vector or a two-dimensional array of equal size to Z, these values are indices into a color table that can be specified by the RGB_TABLE keyword. If more vertices exist than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.

WINDOW (Get Only)

This property retrieves a reference to the WINDOW object which contains the graphic.

XRANGE

A two-element vector giving the X data range to plot. The default behavior is to plot the entire data range.

YRANGE

A two-element vector giving the Y data range to plot. The default behavior is to plot the entire data range.

ZRANGE

A two-element vector giving the Z data range to plot. The default behavior is to plot the entire data range.

Version History

8.0	Introduced
8.1	Added the following properties: CROSSHAIR, UVALUE, WINDOW, [XYZ]SHOWTEXT, [XYZ]STYLE Added the following methods: Delete, GetData, GetValueAtLocation, SetData
8.2	Added AXES, BACKGROUND_COLOR, BACKGROUND_TRANSPARENCY, CLIP properties.
8.2.1	[XYZ]TICKUNITS accepts exponent as a value. Added ANTIALIAS property.

SURFACE

Example

Additional Examples

Syntax

Keywords

Properties

Methods

Return Value

Arguments

Z

X

Y

Keywords

AXIS_STYLE

BUFFER

CURRENT

DEVICE

DIMENSIONS

LAYOUT

LOCATION

MARGIN

NODATA

OVERPLOT

POSITION

TEXTURE_IMAGE

WINDOW_TITLE

Properties

ANTIALIAS

ASPECT_RATIO

ASPECT_Z

AXES (Get Only)

BACKGROUND_COLOR

BACKGROUND_TRANSPARENCY

BOTTOM_COLOR

CLIP

COLOR

CROSSHAIR (Get Only)

DEPTH_CUE

FONT_COLOR

FONT_NAME

FONT_SIZE

FONT_STYLE

HIDDEN_LINES

HIDE

LINESTYLE

MAX_VALUE

MIN_VALUE

NAME

PERSPECTIVE

RGB_TABLE

SHADING

SHOW_SKIRT

SKIRT

STYLE

TEXTURE_INTERP

THICK

TITLE

TRANSPARENCY

UVALUE

VERT_COLORS

WINDOW (Get Only)

XRANGE

YRANGE

ZRANGE

Version History

See Also